Security News
GitHub Removes Malicious Pull Requests Targeting Open Source Repositories
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
react-docgen-typescript
Advanced tools
[![Build Status](https://github.com/styleguidist/react-docgen-typescript/actions/workflows/nodejs.yml/badge.svg)](https://github.com/styleguidist/react-docgen-typescript/actions/workflows/nodejs.yml)
The react-docgen-typescript package is a tool for extracting documentation from TypeScript React components. It parses TypeScript files and generates JSON output that describes the components, their props, methods, and other relevant information. This is particularly useful for creating documentation websites or integrating with other tools that require component metadata.
Extracting Prop Types
This feature allows you to extract prop types from a TypeScript React component. The `parse` function reads the component file and returns a JSON object containing detailed information about the component's props.
const docgen = require('react-docgen-typescript');
const options = { savePropValueAsString: true };
const componentInfo = docgen.parse('path/to/your/component.tsx', options);
console.log(JSON.stringify(componentInfo, null, 2));
Customizing Parser Options
This feature allows you to customize the parser options to fit your needs. For example, you can choose to extract literal values from enums or remove `undefined` from optional props.
const docgen = require('react-docgen-typescript');
const options = { shouldExtractLiteralValuesFromEnum: true, shouldRemoveUndefinedFromOptional: true };
const componentInfo = docgen.parse('path/to/your/component.tsx', options);
console.log(JSON.stringify(componentInfo, null, 2));
Generating Documentation for Multiple Files
This feature allows you to generate documentation for multiple files at once. You can pass an array of file paths to the `parse` function, and it will return a combined JSON object with information about all the components.
const docgen = require('react-docgen-typescript');
const options = { savePropValueAsString: true };
const files = ['path/to/your/component1.tsx', 'path/to/your/component2.tsx'];
const componentInfo = docgen.parse(files, options);
console.log(JSON.stringify(componentInfo, null, 2));
react-docgen is a similar tool that extracts documentation from React components, but it is designed for JavaScript rather than TypeScript. It parses the component files and generates JSON output describing the components. While it is powerful, it lacks the TypeScript-specific features of react-docgen-typescript.
typedoc is a documentation generator for TypeScript projects. It can generate HTML or JSON documentation for TypeScript code, including React components. While it is more general-purpose compared to react-docgen-typescript, it can be used to document a wider range of TypeScript code, not just React components.
ts-morph is a TypeScript compiler API wrapper that allows for easy manipulation and analysis of TypeScript code. While it is not specifically designed for generating documentation, it can be used to extract information from TypeScript code, including React components, and generate custom documentation.
A simple parser for React properties defined in TypeScript instead of propTypes.
It can be used with React Styleguidist.
npm install --save-dev react-docgen-typescript
To parse a file for docgen information use the parse
function.
const docgen = require("react-docgen-typescript");
const options = {
savePropValueAsString: true,
};
// Parse a file for docgen info
docgen.parse("./path/to/component", options);
If you want to customize the typescript configuration or docgen options, this package exports a variety of ways to create custom parsers.
const docgen = require("react-docgen-typescript");
// Create a parser with the default typescript config and custom docgen options
const customParser = docgen.withDefaultConfig(options);
const docs = customParser.parse("./path/to/component");
// Create a parser with the custom typescript and custom docgen options
const customCompilerOptionsParser = docgen.withCompilerOptions(
{ esModuleInterop: true },
options
);
// Create a parser with using your typescript config
const tsConfigParser = docgen.withCustomConfig("./tsconfig.json", {
savePropValueAsString: true,
});
Include following line in your styleguide.config.js
:
module.exports = {
propsParser: require("react-docgen-typescript").withDefaultConfig([
parserOptions,
]).parse,
};
or if you want to use custom tsconfig file
module.exports = {
propsParser: require("react-docgen-typescript").withCustomConfig(
"./tsconfig.json",
[parserOptions]
).parse,
};
propFilter
The propFilter
option allows you to omit certain props from documentation generation.
You can either provide and object with some of our pre-configured filters:
interface FilterOptions {
skipPropsWithName?: string[] | string;
skipPropsWithoutDoc?: boolean;
}
const options = {
propFilter: {
skipPropsWithName: ['as', 'id'];
skipPropsWithoutDoc: true;
}
}
If you do not want to print out all the HTML attributes of a component typed like the following:
const MyComponent: React.FC<React.HTMLAttributes<HTMLDivElement>> = ()...
you can provide a propFilter
function and do the filtering logic yourself.
type PropFilter = (prop: PropItem, component: Component) => boolean;
const options = {
propFilter: (prop: PropItem, component: Component) => {
if (prop.declarations !== undefined && prop.declarations.length > 0) {
const hasPropAdditionalDescription = prop.declarations.find((declaration) => {
return !declaration.fileName.includes("node_modules");
});
return Boolean(hasPropAdditionalDescription);
}
return true;
},
};
Note: children
without a doc comment will not be documented.
componentNameResolver
(exp: ts.Symbol, source: ts.SourceFile) => string | undefined | null | false;
If a string is returned, then the component will use that name. Else it will fallback to the default logic of parser.
shouldExtractLiteralValuesFromEnum
: booleanIf set to true, string enums and unions will be converted to docgen enum format. Useful if you use Storybook and want to generate knobs automatically using addon-smart-knobs.
shouldExtractValuesFromUnion
: booleanIf set to true, every unions will be converted to docgen enum format.
skipChildrenPropWithoutDoc
: boolean (default: true
)If set to false the docs for the children
prop will be generated even without an explicit description.
shouldRemoveUndefinedFromOptional
: booleanIf set to true, types that are optional will not display " | undefined" in the type.
savePropValueAsString
: booleanIf set to true, defaultValue to props will be string. Example:
Component.defaultProps = {
counter: 123,
disabled: false,
};
Will return:
counter: {
defaultValue: '123',
required: true,
type: 'number'
},
disabled: {
defaultValue: 'false',
required: true,
type: 'boolean'
}
Styled components example:
componentNameResolver: (exp, source) =>
exp.getName() === "StyledComponentClass" && getDefaultExportForFile(source);
The parser exports
getDefaultExportForFile
helper through its public API.
In the example folder you can see React Styleguidist integration.
Warning: only named exports are supported. If your project uses default exports, you still need to include named exports for react-docgen-typescript
.
The component Column.tsx
import * as React from "react";
import { Component } from "react";
/**
* Column properties.
*/
export interface IColumnProps {
/** prop1 description */
prop1?: string;
/** prop2 description */
prop2: number;
/**
* prop3 description
*/
prop3: () => void;
/** prop4 description */
prop4: "option1" | "option2" | "option3";
}
/**
* Form column.
*/
export class Column extends Component<IColumnProps, {}> {
render() {
return <div>Test</div>;
}
}
Will generate the following stylesheet:
The functional component Grid.tsx
import * as React from "react";
/**
* Grid properties.
*/
export interface IGridProps {
/** prop1 description */
prop1?: string;
/** prop2 description */
prop2: number;
/**
* prop3 description
*/
prop3: () => void;
/** Working grid description */
prop4: "option1" | "option2" | "option3";
}
/**
* Form Grid.
*/
export const Grid = (props: IGridProps) => {
const smaller = () => {
return;
};
return <div>Grid</div>;
};
Will generate the following stylesheet:
The typescript is pretty complex and there are many different ways how to define components and their props so it's realy hard to support all these use cases. That means only one thing, contributions are highly welcome. Just keep in mind that each PR should also include tests for the part it's fixing.
Thanks to all contributors without their help there wouldn't be a single bug fixed or feature implemented. Check the contributors tab to find out more. All those people supported this project. THANK YOU!
The integration with React Styleguidist wouldn't be possible without Vyacheslav Slinko pull request #118 at React Styleguidist.
FAQs
[![Build Status](https://github.com/styleguidist/react-docgen-typescript/actions/workflows/nodejs.yml/badge.svg)](https://github.com/styleguidist/react-docgen-typescript/actions/workflows/nodejs.yml)
The npm package react-docgen-typescript receives a total of 917,085 weekly downloads. As such, react-docgen-typescript popularity was classified as popular.
We found that react-docgen-typescript demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.